<!-- HTML header for doxygen 1.9.4-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>yyjson: Data Structures</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only-darkmode-toggle.css" rel="stylesheet" type="text/css"/>
<link href="yyjson-style.css" rel="stylesheet" type="text/css"/>
<!-- css awesome -->
 <script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
 <script type="text/javascript">
     DoxygenAwesomeDarkModeToggle.init()
 </script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname"><a href="index.html">yyjson</a><span id="projectnumber">&#160;0.10.0</span>
   </div>
   <div id="projectbrief">A high performance C JSON library.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('md_doc__data_structure.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Data Structures </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p >yyjson consists of two types of data structures: immutable and mutable.</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone"></th><th class="markdownTableHeadNone">Immutable   </th><th class="markdownTableHeadNone">Mutable    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">Document   </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__doc">yyjson_doc</a>   </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__mut__doc">yyjson_mut_doc</a>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">Value   </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__val">yyjson_val</a>   </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a>   </td></tr>
</table>
<ul>
<li>Immutable data structures are returned when reading a JSON document. They cannot be modified.</li>
<li>Mutable data structures are created when building a JSON document. They can be modified.</li>
<li>yyjson also provides some functions to convert between these two types of data structures.</li>
</ul>
<p >Please note that the data structures described in this document are considered private, and it is recommended to use the public API to access them.</p>
<hr  />
 <h1><a class="anchor" id="autotoc_md83"></a>
Immutable Value</h1>
<p >Each JSON value is stored in an immutable <code><a class="el" href="yyjson_8h.html#structyyjson__val">yyjson_val</a></code> struct: </p><div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code hl_struct" href="yyjson_8h.html#structyyjson__val">yyjson_val</a> {</div>
<div class="line">    uint64_t <a class="code hl_variable" href="yyjson_8h.html#ab589c80e05e4e65fa28e23acc1ee8255">tag</a>;</div>
<div class="line">    <span class="keyword">union </span>{</div>
<div class="line">        uint64_t    u64;</div>
<div class="line">        int64_t     i64;</div>
<div class="line">        <span class="keywordtype">double</span>      f64;</div>
<div class="line">        <span class="keyword">const</span> <span class="keywordtype">char</span> *str;</div>
<div class="line">        <span class="keywordtype">void</span>       *ptr;</div>
<div class="line">        <span class="keywordtype">size_t</span>      ofs;</div>
<div class="line">    } <a class="code hl_variable" href="yyjson_8h.html#a3a07ac3ac97c66ae9b23efeab600d013">uni</a>;</div>
<div class="line">}</div>
<div class="ttc" id="ayyjson_8h_html_a3a07ac3ac97c66ae9b23efeab600d013"><div class="ttname"><a href="yyjson_8h.html#a3a07ac3ac97c66ae9b23efeab600d013">yyjson_val::uni</a></div><div class="ttdeci">yyjson_val_uni uni</div><div class="ttdef"><b>Definition:</b> yyjson.h:4516</div></div>
<div class="ttc" id="ayyjson_8h_html_ab589c80e05e4e65fa28e23acc1ee8255"><div class="ttname"><a href="yyjson_8h.html#ab589c80e05e4e65fa28e23acc1ee8255">yyjson_val::tag</a></div><div class="ttdeci">uint64_t tag</div><div class="ttdef"><b>Definition:</b> yyjson.h:4515</div></div>
<div class="ttc" id="ayyjson_8h_html_structyyjson__val"><div class="ttname"><a href="yyjson_8h.html#structyyjson__val">yyjson_val</a></div><div class="ttdef"><b>Definition:</b> yyjson.h:4514</div></div>
</div><!-- fragment --><p> <img src="struct_ival.svg" alt="" style="pointer-events: none;" class="inline" title="yyjson_val"/>    </p>
<p >The type of the value is stored in the lower 8 bits of the <code>tag</code>.<br  />
 The size of the value, such as string length, object size, or array size, is stored in the higher 56 bits of the <code>tag</code>.</p>
<p >Modern 64-bit processors are typically limited to supporting fewer than 64 bits for RAM addresses (<a href="https://en.wikipedia.org/wiki/RAM_limit">Wikipedia</a>). For example, Intel64, AMD64, and ARMv8 have a 52-bit (4PB) physical address limit. Therefore, it is safe to store the type and size information within the 64-bit <code>tag</code>.</p>
<h1><a class="anchor" id="autotoc_md84"></a>
Immutable Document</h1>
<p >A JSON document stores all strings in a <b>contiguous</b> memory area.<br  />
 Each string is unescaped in-place and ended with a null-terminator.<br  />
 For example:</p>
<div class="image">
<object type="image/svg+xml" data="struct_idoc1.svg" style="pointer-events: none;"></object>
<div class="caption">
yyjson_doc</div></div>
    <p >A JSON document stores all values in another <b>contiguous</b> memory area.<br  />
 The <code>object</code> and <code>array</code> containers store their own memory usage, allowing easy traversal of the child values.<br  />
 For example:</p>
<div class="image">
<object type="image/svg+xml" data="struct_idoc2.svg" style="pointer-events: none;"></object>
<div class="caption">
yyjson_doc</div></div>
    <hr  />
 <h1><a class="anchor" id="autotoc_md86"></a>
Mutable Value</h1>
<p >Each mutable JSON value is stored in an <code><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></code> struct: </p><div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code hl_struct" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a> {</div>
<div class="line">    uint64_t <a class="code hl_variable" href="yyjson_8h.html#a5fd1ae5bada624c9687acce330eef7aa">tag</a>;</div>
<div class="line">    <span class="keyword">union </span>{</div>
<div class="line">        uint64_t    u64;</div>
<div class="line">        int64_t     i64;</div>
<div class="line">        <span class="keywordtype">double</span>      f64;</div>
<div class="line">        <span class="keyword">const</span> <span class="keywordtype">char</span> *str;</div>
<div class="line">        <span class="keywordtype">void</span>       *ptr;</div>
<div class="line">        <span class="keywordtype">size_t</span>      ofs;</div>
<div class="line">    } <a class="code hl_variable" href="yyjson_8h.html#a2f30e3958bf136b4e8453a0e78b43d0f">uni</a>;</div>
<div class="line">    <a class="code hl_struct" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a> *<a class="code hl_variable" href="yyjson_8h.html#a172090776a18e45190c933fb3294c07c">next</a>;</div>
<div class="line">}</div>
<div class="ttc" id="ayyjson_8h_html_a172090776a18e45190c933fb3294c07c"><div class="ttname"><a href="yyjson_8h.html#a172090776a18e45190c933fb3294c07c">yyjson_mut_val::next</a></div><div class="ttdeci">yyjson_mut_val * next</div><div class="ttdef"><b>Definition:</b> yyjson.h:5284</div></div>
<div class="ttc" id="ayyjson_8h_html_a2f30e3958bf136b4e8453a0e78b43d0f"><div class="ttname"><a href="yyjson_8h.html#a2f30e3958bf136b4e8453a0e78b43d0f">yyjson_mut_val::uni</a></div><div class="ttdeci">yyjson_val_uni uni</div><div class="ttdef"><b>Definition:</b> yyjson.h:5283</div></div>
<div class="ttc" id="ayyjson_8h_html_a5fd1ae5bada624c9687acce330eef7aa"><div class="ttname"><a href="yyjson_8h.html#a5fd1ae5bada624c9687acce330eef7aa">yyjson_mut_val::tag</a></div><div class="ttdeci">uint64_t tag</div><div class="ttdef"><b>Definition:</b> yyjson.h:5282</div></div>
<div class="ttc" id="ayyjson_8h_html_structyyjson__mut__val"><div class="ttname"><a href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></div><div class="ttdef"><b>Definition:</b> yyjson.h:5281</div></div>
</div><!-- fragment --><p> <img src="struct_mval.svg" alt="" style="pointer-events: none;" class="inline" title="yyjson_mut_val"/>    </p>
<p >The <code>tag</code> and <code>uni</code> fields are the same as the immutable value, and the <code>next</code> field is used to build a linked list.</p>
<h1><a class="anchor" id="autotoc_md87"></a>
Mutable Document</h1>
<p >A mutable JSON document is composed of multiple <code><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></code>.</p>
<p >The child values of an <code>object</code> or <code>array</code> are linked as a cycle,<br  />
 the parent holds the <b>tail</b> of the circular linked list, enabling yyjson to perform operations <code>append</code>, <code>prepend</code> and <code>remove_first</code> in constant time.</p>
<p >For example:</p>
<div class="image">
<object type="image/svg+xml" data="struct_mdoc.svg" style="pointer-events: none;"></object>
<div class="caption">
yyjson_mut_doc</div></div>
    <hr  />
 <h1><a class="anchor" id="autotoc_md89"></a>
Memory Management</h1>
<p >A JSON document (<code><a class="el" href="yyjson_8h.html#structyyjson__doc">yyjson_doc</a></code>, <code><a class="el" href="yyjson_8h.html#structyyjson__mut__doc">yyjson_mut_doc</a></code>) is responsible for managing the memory of all its JSON values and strings. When a document it is no longer needed, it is important for the user to call <code><a class="el" href="yyjson_8h.html#adad98bd766cf52d99f2c54dcb120786d">yyjson_doc_free()</a></code> or <code><a class="el" href="yyjson_8h.html#a7a5f504993031f912d06777b8a7b5aff">yyjson_mut_doc_free()</a></code> to free the memory associated with it.</p>
<p >A JSON value (<code><a class="el" href="yyjson_8h.html#structyyjson__val">yyjson_val</a></code>, <code><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></code>) has the same lifetime as its document. The memory is managed by its document and and cannot be freed independently.</p>
<p >For more information, refer to the <a class="el" href="md_doc__a_p_i.html">API documentation</a>. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.9.4-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Documentation for <a href="https://github.com/ibireme/yyjson" target="_blank">yyjson</a>, generated by <a href="https://www.doxygen.org/index.html" target="_blank">doxygen</a> 1.9.4 </li>
  </ul>
</div>
</body>
</html>
